Inside Macintosh: Mac OS 8 Toolbox Reference /

Chapter 2 - Control Manager Reference / Control Manager Functions

Creating and Removing Controls /

GetNewControl

CHANGED WITH THE APPEARANCE MANAGER

Creates a control from a description in a control ('CNTL') resource.

pascal ControlHandle GetNewControl (
                     SInt16 resourceID,
                     WindowPtr owningWindow);

resourceID

The resource ID of a control resource; see Table 2-1.

owningWindow

A pointer to the window in which you want to place the control.

function result

Returns a handle to the control created from the specified control resource. If GetNewControl can't read the control resource from the resource file, it returns nil.

DISCUSSION

The GetNewControl function creates a control structure from the information in the specified control resource, adds the control structure to the control list for the specified window, and returns as its function result a handle to the control. You use this handle when referring to the control in most other Control Manager functions. After making a copy of the control resource, GetNewControl releases the memory occupied by the original control resource before returning.

The control resource specifies the rectangle for the control, its initial setting, its visibility state, its maximum and minimum settings, its control definition ID, a reference value, and its title (if any). After you use GetNewControl to create the control, you can change the control characteristics with other Control Manager functions.

If the control resource specifies that the control should be visible, the Control Manager draws the control. If the control resource specifies that the control should initially be invisible, you can use the function ShowControl to make the control visible.

When an embedding hierarchy is established within a window, GetNewControl automatically embeds the newly created control in the root control of the owning window. See "Embedding Controls".

If you are using standard system controls, default colors are used and the control color table resource is ignored. To use colors other than the default colors, you must write your own custom control definition function.

SEE ALSO

NewControl.

WHEN THE APPEARANCE MANAGER IS NOT AVAILABLE

GetNewControl does not embed the newly created control in the root control of the owning window because embedding hierarchies are not supported.